To be able to use a true Mac application you should not have to read a big user manual. I imagine it should be possible to figure out everything about the graphical interface of TPlot from a little experimentation and a quick reading of the "About TPlot..." menu item in the standalone TPlot application:
This is basically all that needs to be said about the graphical interface. Of course, this simplicity is achieved partly by sacrificing features. If you want to be able to choose the size of your tick marks this is not the application for you (try gnuplot instead; it's also free!).
Nonetheless, there are a few subtleties and not-so-obvious points about what the program does and doesn't do, which warrant a more detailed explanation. These fall mostly in two areas: opening and saving files, and using the Cut-Copy-Paste features.
2. Opening and saving files:
Currently (v. 1.0) all that is saved when you choose Save or Save As is the data sets for the plot, and they are put in "spreadsheet-style" format as indicated above. A later version might be able to save the actual figure on the screen (for instance, in PICT format); for now, if you really want the screen image you can put it in the Clipboard using "Copy as PICT" from the Edit menu (see below) and use some other application to save it separately.
The end-of-line character in files saved by TPlot is \r (the usual Mac carriage return), rather than \n (most other systems' newline). This is to allow you to open the files using SimpleText to add, for instance, a comment at the top describing the contents of the file. If you want to export the file to another system, use a text editor (BBEdit, for instance) to replace the \r's by \n's. TPlot itself can read files with \r's or \n's indiscriminately. Likewise, the columns may be separated by blanks or tabs; when saving, TPlot uses tabs as the separators. It is extremely easy to import or export data from TPlot to Excel or vice-versa. (Just remember to save your Excel document as a text file.)
Files representing multiple parametric plots must have as the first nonblank line after the (optional) comment the sequence "!mpplot npts1 npts2 ...", where npts1, npts2,... up to npts4 are the number of points in each of the plots. As stated above, the columns in a multiple parametric plot file represent, in order, x1, y1, x2, y2,... up to x4, y4. (Obviously, x1 and y1 must have the same number of points, npts1, and so on.)
3. The Edit menu:
At one point I realized it would be really useful to be able to combine plots from different files into a single graph, for comparison purposes. This version of TPlot allows you to do that by using Cut and/or Copy, and Paste, in what is hopefully a "natural" way, but with perhaps a few somewhat unusual twists.
• To select a plot or plots from a window (that you may want to cut or copy into another window) you can choose "Select..." from the Edit menu (a shortcut will be discussed in a moment). This brings up a dialog box with four checkboxes, one for each plot (if there are less than four plots, the extra boxes are disabled). The plots are numbered one through four, and correspond to the basic color sequence mentioned above, i.e., first plot--blue, second plot--red, third plot--green, and fourth plot--magenta. When you check a box the corresponding plot in the window is drawn in a different pen pattern, to let you know that it has been selected (if that is not the plot you wanted, just uncheck the box).
When you have selected the plots you wanted, click Cut or Copy on the same dialog box. Cut will remove the selected plots from the picture and put them in the Clipboard, so you can paste them into another window; Copy will also put them in the Clipboard, but will not delete them from the original window.
• If a window contains a single plot you may think of it as being always selected by default; in that case, you can choose Cut or Copy directly, from the Edit menu or through the command-X and command-C key equivalents. Cut will remove the plot and leave you with a blank (untitled) window, Copy will just put it in the Clipboard ready to paste.
• If a window contains more than one plot and you choose Cut or Copy from the edit menu (or their command-key equivalents), the Selection dialog box will be brought up automatically, to let you select the plots and complete the Cut or Copy operation from the dialog box itself. This means that command-C or command-X can in fact be used as a shortcut to bring up the Selection dialog box, and that the Selection... item in the Edit menu is really unnecessary. I thought of removing it altogether, but decided to leave it there to avoid confusing possible users who would not read this and might be puzzled by the absence from the graphical interface of any obvious way to select plots.
• To paste a plot into a window, just choose paste (or command-V) when that window is the front window and active. You may paste either into a blank window (created, for instance, using the command "New" under the File menu) or into a window that already has other (less than four) plots.
The new plots are added "after" the ones that are already there. For instance, suppose you have a window with two plots and you attempt to paste three plots which you have copied from another window. Say that the plots in the Clipboard were numbers 1, 3 and 4 in their original window. After the paste operation, plot 1 becomes 3 (after the two which were already in the destination window), plot 3 becomes 4, and plot 4 is simply not pasted, since the number of plots in any window cannot exceed 4 (all three plots are still available in the Clipboard, however, for any subsequent paste operation).
This renumbering of the plots means that plots may, and frequently will, change color when they are pasted from one window into another one. In the example above, the two new plots are drawn in green and magenta instead of their original colors of blue and green. There is no simple way around this that I can see; you just have to pay attention.
• Plots will also change color when you cut from an existing window any plot other than the last one; the remaining plots are "renumbered" and recolored accordingly. If you paste back the plot you just cut, it goes to the "back of the line", and that probably means a different color than it had originally!
To further add to the (possible) confusion, when you cut from or paste into a window, everything is rescaled and the window is resized back to the default size.
• The "Copy as PICT" command: The last command in the Edit menu takes a snapshot of the currently active window and puts it in the Clipboard. You can then switch to any application that allows you to paste "PICT" images (word processor, drawing or page layout program...) and paste it and save it, perhaps after laying out a page with several other plots, text, etc. Note that you get literally a screen snapshot, with a resolution of 72 dpi: it will look all right on a computer screen but it will look lousy when printed. Someday I may figure out how to get TPlot to produce high-quality, postscript images---or I may actually read the gnuplot manual instead!
4. The View menu.
• The "Set range..." command: This just brings up a dialog so you can choose the range of values of x and y that you want to display; it gives you a bit more precision than zooming in with the mouse (although it is slower, of course); it also provides you with a way to "zoom out".
Nifty little feature: the default values displayed in the Set Range dialog are the actual maximum and minimum values of the x's and y's for your original data set.
• The "Proportional scale" command: Draws the window using the same scale for both axes. The vertical axis scale is chosen as the reference.
Other resizing and zooming can be done directly with the mouse, as explained in the "About TPlot..." box. To zoom in with the mouse, click on the plot and drag around; a rectangle appears which is expanded into a separate window when you release the mouse.
5. Bugs and other features.
(a) Bugs...
• If you make the plot window very small, the program may choose somewhat strange labels which may even overlap in part. This does not bother me anymore as much as it did a few months ago, so I may never get around to fixing it. Basically, the problem usually goes away if you just make the window a little bigger.
• If you save a plot under a different name, the title of the window changes to the new name, and any windows subsequently derived from it by zooming also inherit the new name. So far, so good. However, any windows derived from the same plot that you may have had on the screen before you renamed it (again, zoom windows, typically) do not get their name changed when you save the plot under another name; only the front window gets renamed. I may actually get around to fixing this one one of these days.
• If you zoom in too far, you may start getting lines in your plot that do not actually belong there. There is no simple fix for that one. Basically, what happens (I think) is this: you have zoomed in so much that some of your data points have been pushed away beyond the boundaries of the "virtual screen beyond your screen," so a segment connecting them can show up pretty much anywhere.
Just don't zoom in that much! No, seriously, the fact is that by the time this problem happens--if it happens--you have probably exceeded the accuracy of your data and are looking at regions with few if any actual data points.
• The command "Print One" is supposed to let you print one copy of your front window without bothering you with a dialog, using the previously saved settings from your latest print job (or the default settings, if you haven't used the Print or Page Setup dialogs yet). Unfortunately, for reasons that completely escape me, if your last print job requested n copies, Print One will also give you n copies (instead of just one, as it should). This is pretty obscure, since most people don't even know about this Print One command in the first place. I only put it there because Jim Trudeau told me to.
• The program does not check whether your plot is too big for the paper you are printing on. It just prints whatever fits and cheerfully ignores the rest. If in doubt, try previewing.
• You can't use Cut/Copy and Paste for text items in dialog windows.
• The program requires system 7 but does not check to see whether it is actually there, so I imagine that if you try to run it under system 6 it will crash and burn unceremoniously. I know, I know, it would only take me a couple of lines of code and another dialog resource to have it check for system 7 and exit gracefully if it is not there, but I feel terribly unmotivated to do it. Does anybody still run system 6 anyway?
• Random crashes: The program does some minimal amount of error checking at this point, but does not issue error reports for everything that could possibly go wrong. Also, I do not exactly practice "safe" (meaning: "paranoid") coding; I try to watch out for obvious pitfalls, but I imagine that you can never be prepared for the unexpected anyway. If this was a commercial product I would actually be getting paid to try to make it as stable as humanly possible, but as it is all I can say is that it no longer crashes for me, but I'm sure you could get it to crash if you really wanted to.
If you do run into a repeatable bug, I ask you to please let me know, with as much information as possible. You can even send me a copy of your code and I'll put it through the paces. Of course, it's even better if you do the debugging yourself and then let me know where the error is! :-) Either way, I'm looking forward to hearing from any and all users (somebody will use this, won't they?).
• There is no Undo, no Select All and no Revert menu commands. I found out that living without them was actually a lot easier than trying to figure out how to implement them...
(b) Things I would like to add:
It might be nice to have a "crosshairs" feature so you can point with the mouse to some point in the window and see its coordinates. Don't hold your breath, though...
6. Acknowledgements:
My colleague Bill Harter taught me the secrets of XOR drawing. Without him, there wouldn't be a marquee for zooming in.
I learned a lot (but probably not enough!) from the books "Macintosh Programming Primer" by Dave Mark and Reed Cartwright, and "Programming Starter Kit for Macintosh" by Jim Trudeau. Some of the simple utility functions I just borrowed, with minor changes, from PSKM's EasyApp (that's OK, isn't it?).
My wife Tamara was a dedicated beta tester and made all the icons besides. (And now, if you've read this far, you may guess what the T in TPlot stands for...)
